home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 May: Tool Chest / Dev.CD May 98 TC.toast / Tool Chest / Testing & Debugging / Mac OS Development Toolkit / Automation Essentials 2.3.0 / Host Automation Folder / VU External Tool libs / Ivy.vulib < prev    next >
Encoding:
Text File  |  1998-03-19  |  39.7 KB  |  1,569 lines  |  [TEXT/MPS ]

  1. (*
  2.         File:        Ivy Task Library for Virtual User 2.1 version 1.2b3
  3.  
  4.         Contains:    The Ivy 1.2 Virtual User tool declaration.
  5.  
  6.         Written by:    Rich Millet
  7.  
  8.         Copyright:    © 1994-1997 by Apple Computer, Inc., all rights reserved.
  9.  
  10.  *)
  11.  
  12. #
  13. #    Change history (most recent first):
  14. #        Version      Date        Who        Comments
  15. #        =======    ========    ===        =============
  16. #        1.4.0    02/03/97    JAS        Added 'vers' resources to library.
  17. #                                    These should always match tool version when tool is revved.
  18. #
  19. #
  20.  
  21. Libraries "Ivy Tool Declaration.vulib";
  22.  
  23. #--------------------------------------------------------------------------------------------------
  24.  
  25. #
  26. #    find Δ/•#∂tIV≈∂)∞/
  27. #    find /IV[a-z_0-9]+/
  28. #    mark -y § "`catenate "{Target}".§`"
  29. #    find Δ§
  30. #
  31.  
  32. #    INITIALIZATION TASKS
  33.  
  34. #    IVInit( theLocation, theBoolean := false )
  35. #
  36. #    Purpose:
  37. #        To open and initialize the Ivy application.
  38. #
  39. #    Inputs:
  40. #        theLocation    -     a Boolean value indicating whether you want Ivy opened on the
  41. #                        target or host machine.  Passing a true value opens Ivy on the
  42. #                        target.  Passing a false value opens Ivy on the host.
  43. #
  44. #        theBoolean    _    Ignore this parameter, unless you are using scripts written for the Ivy 1.0 task library.
  45. #                        It is a Boolean value indicating whether or not to support the Ivy 1.0
  46. #                        style of returning task results. A true value will ensure compatibility with
  47. #                        scripts written using the Ivy 1.0 task library.
  48. #
  49. #    Outputs:
  50. #        result        -     a Boolean value indicating success or failure; true = success, false = failure.
  51. #
  52. #    Notes:
  53. #         Your script must call this task before using any other Ivy tasks!
  54. #
  55. #         This task initializes the image information globals(constants). Use these globals to index
  56. #        the list of values returned by the 'IVGetImageFileInfo' task.  It also initializes font
  57. #        style constants that you should use when writing scripts with the IVLocateString() task.
  58. #
  59. #    Example:
  60. #
  61. #        result := IVInit( false );
  62. #        if ( result <> true )
  63. #        begin
  64. #            # Handle error here.
  65. #        end;
  66. #
  67. Task IVInit( theLocation, theBoolean := false ) 
  68. begin
  69.     global kIVLibraryVersion        := 120;
  70.     global kIVLibraryVersionString    := '1.2';
  71.     
  72.     global kImageFrame            := 1;
  73.     global kIvyVersion            := 2;
  74.     global kImageSize            := 3;
  75.     global kImageBitMapChecksum    := 4;
  76.     global kImageRGBChecksum    := 5;
  77.     global kImagePixelCount        := 6;
  78.     global kImageBitDepth        := 7;
  79.     global kImageDateStamp        := 8;
  80.     global kImageTimeStamp         := 9;
  81.     
  82.     global kNormal        := 0;
  83.     global kBold        := 1;
  84.     global kItalic        := 2;
  85.     global kUnderline    := 4;
  86.     global kOutline        := 8;
  87.     global kShadow        := 16;
  88.     global kCondense    := 32;
  89.     global kExtend        := 64;
  90.                                                         # if true, the Ivy 1.1 tasks return the entire external tool result list.
  91.     global gIVResultList := theBoolean;                    # Set to true for backward compatibility with scripts written for the
  92.                                                         # Ivy 1.0 task library.
  93.                                                                                                         
  94.     resultList := Ivy( "INITIALIZE", theLocation );      # true launches on the target, false on the host.
  95.     global gIVError := resultList;
  96.     
  97.     if ( resultList[1] <> 0 )
  98.         return false;
  99.     
  100.     resultList := Ivy( "IVInit" );                      # prepares Ivy's core routines.
  101.     global gIVError := resultList;
  102.     
  103.     if ( resultList[1] <> 0 )
  104.         return false;
  105.         
  106.     toolVersionString := IVGetToolVersion();
  107.     
  108.     if ( toolVersionString[1] < kIVLibraryVersion )
  109.     begin
  110.         println "IVInit - The Ivy external tool is out of date relative to Ivy's task library.";
  111.         println "IVInit - The Ivy external tool version is : ", toolVersionString[3];
  112.         println "IVInit - Upgrade the Ivy external tool to a version greater than or equal to ", kIVLibraryVersionString;
  113.         return false;
  114.     end;
  115.     
  116.     IVSetExceptionHandler();                            # set up default exception handling;
  117.     IVStopWaitForImage();                                # clear any pending ‘wait for image’ tasks.
  118.     
  119.     return true;
  120. end;
  121.  
  122.  
  123. #    IVError()
  124. #
  125. #    Purpose:
  126. #        To return the result list of the last Ivy task called.
  127. #
  128. #    Inputs:
  129. #        None.
  130. #
  131. #    Outputs:
  132. #        result        - a list of three values: { errorCode, taskValue, error message }
  133. #        taskValue    - differs for each task.
  134. #
  135. #    Notes:
  136. #         None.
  137. #
  138. #    See also:
  139. #        IVSetExceptionHandler()
  140. #
  141. #    Example:
  142. #
  143. #        errorList := IVError();
  144. #        if ( errorList[1] <> 0 )
  145. #        begin
  146. #            …
  147. #        end;
  148. #
  149. Task IVError()
  150. begin
  151.     return global gIVError;
  152. end;
  153.  
  154.  
  155. #    IVSetExceptionHandler( theHandler := Task IVDefaultHandler )
  156. #
  157. #    Purpose:
  158. #        To install an exception handling task for all Ivy task calls.
  159. #
  160. #    Inputs:
  161. #        theHandler - a task reference. Ivy will call ‘theHandler’ whenever one of its tasks
  162. #                     encounters an error.
  163. #
  164. #    Outputs:
  165. #        None. Does not affect the results of IVError().
  166. #
  167. #    Notes:
  168. #         Does not affect the results of IVError().
  169. #
  170. #    See also:
  171. #        IVDefaultHandler()
  172. #        IVError();
  173. #
  174. #    Example:
  175. #
  176. #        IVSetExceptionHandler( Task YourTaskName );
  177. #
  178. Task IVSetExceptionHandler( theHandler := Task IVDefaultHandler )
  179. begin
  180.     global gIVExceptionHandler := theHandler;
  181. end;
  182.  
  183.  
  184. #    IVGetExceptionHandler()
  185. #
  186. #    Purpose:
  187. #        To get a task reference to the current Ivy exception handler.
  188. #
  189. #    Inputs:
  190. #        None.
  191. #
  192. #    Outputs:
  193. #        result - a task reference to Ivy’s current exception handler.
  194. #
  195. #    Notes:
  196. #         Does not affect the results of IVError();
  197. #
  198. #    See also:
  199. #        IVSetExceptionHandler()
  200. #        IVDefaultHandler()
  201. #
  202. #    Example:
  203. #
  204. #        exceptionHandler := IVGetExceptionHandler();
  205. #
  206. Task IVGetExceptionHandler()
  207. begin
  208.     global gIVExceptionHandler;
  209.     
  210.     if ( isUndefined( gIVExceptionHandler ) = false )
  211.         return gIVExceptionHandler;
  212.     else
  213.     begin
  214.         println;
  215.         println "### Error - Ivy has not been initialized. See description of IVInit() task.";
  216.         println;
  217.         exit;
  218.     end;
  219. end;
  220.  
  221.  
  222. #    IVDefaultHandler( theResultList )
  223. #
  224. #    Purpose:
  225. #        To be the default Ivy task exception handler.  This handler prints out the error message
  226. #        and returns the task return value.
  227. #
  228. #    Inputs:
  229. #        theResultList    - a list of three values: { errorCode, taskValue, error message }
  230. #
  231. #    Outputs:
  232. #        taskValue        - the ‘taskValue’ of ‘theResultList’. 
  233. #
  234. #    Notes:
  235. #         Applicable notes.
  236. #
  237. #    See also:
  238. #            IVSetExceptionHandler()
  239. #            IVGetExceptionHandler()
  240. #            IVError();
  241. #
  242. Task IVDefaultHandler( theResultList )
  243. begin
  244.     println theResultList;
  245.     
  246.     return theResultList[2];
  247. end;
  248.  
  249.  
  250. #    IVGetToolVersion( )
  251. #
  252. #    Purpose:
  253. #        To find out the version of the external tool.
  254. #
  255. #    Inputs:
  256. #        None.
  257. #
  258. #    Outputs:
  259. #        result - a string containing Ivy's external tool version.
  260. #
  261. #    Notes:
  262. #         Applicable notes.
  263. #
  264. #    Example:
  265. #
  266. #        versionString := IVGetToolVersion();
  267. #
  268. Task IVGetToolVersion( )
  269. begin
  270.     resultList := Ivy( "GETTOOLVERSION" );
  271.     global gIVError := resultList;
  272.     
  273.     versionNumber := Ivy( "IVGETTOOLVERSION" )[2];
  274.     
  275.     return { versionNumber } + resultList[2];
  276. end;
  277.  
  278.  
  279. #    IVQuit( )
  280. #
  281. #    Purpose:
  282. #        To close (or quit) Ivy.
  283. #
  284. #    Inputs:
  285. #        None.
  286. #
  287. #    Outputs:
  288. #        result - undefined.
  289. #
  290. #    Notes:
  291. #         Applicable notes.
  292. #
  293. #    Example:
  294. #
  295. #        IVQuit();
  296. #
  297. Task IVQuit( )
  298. begin
  299.     resultList := Ivy( "QUIT" );
  300.     global gIVError := resultList;
  301.     
  302.     return resultList[2];
  303. end;
  304.  
  305.  
  306. Task HandleResultList( theResultList, theTaskName )
  307. begin
  308.     if ( isUndefined( theResultList ) or ( card theResultList < 2 ) )
  309.     begin
  310.         newResultList := { -1, Undefined, "### Error - An unknown error in Ivy occurred." };
  311.     end;
  312.     else
  313.     begin 
  314.         if ( theResultList[1] <> 0 )
  315.         begin
  316.             if ( isUndefined( theResultList[3] ) )
  317.                 newResultList := { theResultList[1], theResultList[2], theTaskName + " - No description for this error is available." };
  318.             else
  319.                 newResultList := replace( theTaskName + " - " + theResultList[3], 3, theResultList );
  320.         end;
  321.         else
  322.         begin
  323.             newResultList := theResultList;
  324.         end;
  325.     end;
  326.  
  327.     return newResultList;
  328. end;
  329.  
  330.  
  331. #--------------------------------------------------------------------------------------------------
  332.  
  333. #    TASKS TO SEND COMMANDS TO TOOLS LIKE MACSTIME
  334.  
  335. #    IVSetToolCmd( theToolID, theCommand, theContext, theParam1, theParam2, theParam3, theParam4 )
  336. #
  337. #    Purpose:
  338. #        To have Ivy send a command to a tool when Ivy starts looking for or when it detects the
  339. #        appearance of an image. In this version of Ivy, Ivy can send only ONE command; that is, Ivy
  340. #        can NOT send two commands when it starts looking for or detects the appearance of an image.
  341. #
  342. #    Inputs:
  343. #        theToolID - a four character string identifying the tool to receive
  344. #        the command ‘Command’. The string should be the four character Gestalt
  345. #        selector that the tool registered with the Gestalt Manager.
  346. #
  347. #        theContext - a boolean flag.
  348. #
  349. #            false - Ivy will send the command when it starts looking for the image.
  350. #            true  - Ivy will send the command when it detects the appearance of the image.
  351. #        
  352. #        theCommand - an integer identifying which of the tool's commands to execute.
  353. #        
  354. #        theParam1 through theParam4 - the parameters for the ‘theCommand’ request that Ivy
  355. #        sends to the tool.
  356. #
  357. #    Outputs:
  358. #        result - None
  359. #
  360. #    Notes:
  361. #         None
  362. #
  363. #    See also:
  364. #        IVStartWaitForImage()
  365. #        IVStopWaitForImage()
  366. #        IVWaitForImage()
  367. #        IVUnsetToolCmd()
  368. #
  369. #    Example:
  370. #
  371. #        theResult := IVSetToolCmd( 'maxt', 4, true, 0, 0, 0, 0 );
  372. #
  373. #        This example, sets up Ivy to send MacsTime (maxt) a 'StopNow' command when it detects the
  374. #        appearance of an image.
  375. #
  376. Task IVSetToolCmd( theToolID, theCommand, theContext := true, theParam1 := 0, theParam2 := 0, theParam3 := 0, theParam4 := 0 )
  377. begin
  378.     resultList := Ivy( "IVSETTOOLCMD", theToolID, theCommand, theContext, theParam1, theParam2, theParam3, theParam4 );
  379.  
  380.     resultList := HandleResultList( resultList, "IVSetToolCmd" );
  381.     global gIVError := resultList;
  382.     
  383.     if ( resultList[1] <> 0 )
  384.         return Call( IVGetExceptionHandler(), resultList );    
  385.     
  386.     if ( global gIVResultList )
  387.         return resultList;
  388.     else
  389.         return resultList[2];
  390. end;
  391.  
  392.  
  393. #    IVUnsetToolCmd( theToolID )
  394. #
  395. #    Purpose:
  396. #        To unset all tool commands set by the task IVSetToolCmd().  In this version of Ivy, Ivy can
  397. #        send only one command; that is, Ivy can not send two tools commands when it starts looking for or
  398. #        detects the appearance of an image.
  399. #
  400. #    Inputs:
  401. #        theToolID - a four character string identifying the tool to receive
  402. #        the command ‘Command’. The string should be the four character Gestalt
  403. #        selector that the tool registered with the Gestalt Manager.
  404. #
  405. #    Outputs:
  406. #        None.
  407. #
  408. #    Notes:
  409. #         None.
  410. #
  411. #    See also:
  412. #        IVSetToolCmd()
  413. #
  414. #    Example:
  415. #
  416. #        IVUnsetToolCmd( 'maxt' );
  417. #
  418. Task IVUnsetToolCmd( theToolID )
  419. begin
  420.     resultList := Ivy( "IVUNSETTOOLCMD", theToolID );
  421.     
  422.     resultList := HandleResultList( resultList, "IVUnsetToolCmd" );
  423.     global gIVError := resultList;
  424.  
  425.     if ( resultList[1] <> 0 )
  426.     begin
  427.         return Call( IVGetExceptionHandler(), resultList );
  428.     end;
  429.     
  430.     if ( global gIVResultList )
  431.         return resultList;
  432.     else
  433.         return resultList[2];
  434. end;
  435.  
  436.  
  437. #    IVSendToolCmd( theToolID, theCommand, theParam1, theParam2, theParam3, theParam4 )
  438. #
  439. #    Purpose:
  440. #        To get a task reference to the current Ivy exception handler.
  441. #
  442. #    Inputs:
  443. #        theToolID - a four character string identifying the tool to receive
  444. #        the command ‘Command’. The string should be the four character Gestalt
  445. #        selector that the tool registered with the Gestalt Manager.
  446. #        
  447. #        theCommand - an integer identifying which of the tool's commands to execute.
  448. #        
  449. #        theParam1 through theParam4 - the parameters for the ‘theCommand’ request that Ivy
  450. #        sends to the tool.
  451. #
  452. #    Outputs:
  453. #        result - the result of the command 'theCommand'.
  454. #
  455. #    Notes:
  456. #         None.
  457. #
  458. #    See also:
  459. #        IVSetStopImageCmd()
  460. #        IVClearStopImageCmd()
  461. #
  462. #    Example:
  463. #
  464. #        theResult := IVSendToolCmd( 'maxt', 4, 0, 0, 0, 0 );
  465. #
  466. #        This example sends the MacsTime tool (maxt) a 'StopNow' command.
  467. #
  468. Task IVSendToolCmd( theToolID, theCommand, theParam1 := 0, theParam2 := 0, theParam3 := 0, theParam4 := 0 )
  469. begin
  470.     resultList := Ivy( "IVSENDTOOLCMD", theToolID, theCommand, theParam1, theParam2, theParam3, theParam4 );
  471.     
  472.     resultList := HandleResultList( resultList, "IVSendToolCmd" );
  473.     global gIVError := resultList;
  474.  
  475.     if ( resultList[1] <> 0 )
  476.     begin
  477.         return Call( IVGetExceptionHandler(), resultList );
  478.     end;
  479.     
  480.     
  481.     if ( global gIVResultList )
  482.         return resultList;
  483.     else
  484.         return resultList[2];
  485. end;
  486.  
  487.  
  488. #--------------------------------------------------------------------------------------------------
  489.  
  490. #    TASKS TO SET THE CURRENT DIRECTORY AND DELETE FILES
  491.  
  492. #    IVSetDirectory( thePathName )
  493. #
  494. #    Purpose:
  495. #        To sets Ivy’s default file directory.
  496. #
  497. #    Inputs:
  498. #        thePathName    - a string describing a full or partial path name.
  499. #
  500. #    Outputs:
  501. #        result        - a string describing the new full path name.
  502. #
  503. #    Notes:
  504. #         If you never call this task, Ivy's default directory will be the directory in
  505. #        which the Ivy application file resides.
  506. #
  507. #    See also:
  508. #        IVSetDirectory();
  509. #
  510. #    Example:
  511. #
  512. #        result := IVSetDirectory( "HD 80SC:Jane’s Folder:Images:" );
  513. #            
  514. #        errorList := IVError();
  515. #        if ( errorList[1] <> 0 )
  516. #        begin
  517. #            println "Could not set the directory - ", errorList;
  518. #        end;
  519. #
  520. Task IVSetDirectory( thePathname )
  521. begin
  522.     resultList := Ivy( "IVSETDIRECTORY", thePathname );
  523.     
  524.     resultList := HandleResultList( resultList, "IVSetDirectory" );
  525.     global gIVError := resultList;
  526.  
  527.     if ( resultList[1] <> 0 )
  528.     begin
  529.         return Call( IVGetExceptionHandler(), resultList );
  530.     end;
  531.     
  532.     
  533.     if ( global gIVResultList )
  534.         return resultList;
  535.     else
  536.         return resultList[2];
  537. end;
  538.  
  539.  
  540. #    IVGetDirectory()
  541. #
  542. #    Purpose:
  543. #        To get Ivy’s default directory.
  544. #
  545. #    Inputs:
  546. #        None.
  547. #
  548. #    Outputs:
  549. #        result - a string describing Ivy’s default directory.
  550. #
  551. #    Notes:
  552. #         With this task, your script can determine where Ivy is creating and looking for
  553. #        image files.
  554. #
  555. #    See also:
  556. #        IVSetDirectory();
  557. #
  558. #    Example:
  559. #
  560. #        tPathName := IVGetDirectory();
  561. #            
  562. #        errorList := IVError();
  563. #        if ( errorList[1] <> 0 )
  564. #        begin
  565. #            println "Could not get the directory pathname- ", errorList;
  566. #        end;
  567. #
  568. Task IVGetDirectory()
  569. begin
  570.     resultList := Ivy( "IVGETDIRECTORY" );
  571.     
  572.     resultList := HandleResultList( resultList, "IVGetDirectory" );
  573.     global gIVError := resultList;
  574.     
  575.     if ( resultList[1] <> 0 )
  576.     begin
  577.         return Call( IVGetExceptionHandler(), resultList );
  578.     end;
  579.         
  580.     if ( global gIVResultList )
  581.         return resultList;
  582.     else
  583.         return resultList[2];
  584.  end;
  585.  
  586.  
  587. #    IVDeleteImageFile( theFileName )
  588. #
  589. #    Purpose:
  590. #        To delete an image file.
  591. #
  592. #    Inputs:
  593. #        theFileName - a string containing the name of the file to delete.
  594. #
  595. #    Outputs:
  596. #        result        - a Boolean value indicating success or failure; 1 is success and 0 is failure.
  597. #
  598. #    See also:
  599. #        IVCreateImageFile()
  600. #
  601. #    Example:
  602. #
  603. #        result := IVDeleteImageFile( "Pam’s Image File" );
  604. #            
  605. #        errorList := IVError();
  606. #        if ( errorList[1] <> 0 )
  607. #        begin
  608. #            println "Could not delete the image file - ", errorList;
  609. #        end;
  610. #
  611. Task IVDeleteImageFile( theFileName )
  612. begin
  613.     kFileNotFound := -43;
  614.     
  615.     resultList := Ivy( "IVDELETEIMAGE", theFileName );
  616.     
  617.     resultList := HandleResultList( resultList, "IVDeleteImageFile" );
  618.     global gIVError := resultList;
  619.     
  620.     if ( resultList[1] <> 0 and resultList[1] <> kFileNotFound )
  621.     begin
  622.         return Call( IVGetExceptionHandler(), resultList );
  623.     end;
  624.         
  625.     if ( global gIVResultList )
  626.         return resultList;
  627.     else
  628.         return resultList[2];
  629.  end;
  630.  
  631.  
  632. #--------------------------------------------------------------------------------------------------
  633.  
  634.  
  635. # TASKS TO CAPTURE AND COMPARE 'PICT' SCREEN IMAGE FILES
  636.  
  637.  
  638. Task IVRectangleDefined( theRectangle )
  639. begin
  640.     if ( isUndefined( theRectangle ) = true )
  641.         return false;
  642.         
  643.     if ( isUndefined( theRectangle[1] ) or isUndefined( theRectangle[2] ) or
  644.             isUndefined( theRectangle[3] ) or isUndefined( theRectangle[4] ) )
  645.         return false;
  646.         
  647.     return true;
  648. end;
  649.  
  650.  
  651. #    IVCreateImageFile( theFileName, theImageRectangle, theIgnoreRectangles := { } )
  652. #
  653. #    Purpose:
  654. #        To create a file which contains a PICT resource containing a screen image.
  655. #
  656. #    Inputs:
  657. #        theFileName            - a string containing the name of the file to create.
  658. #
  659. #        theImageRectangle    - the rectangle enclosing the screen image to capture; { left, top,
  660. #                              right, bottom }.
  661. #
  662. #        theIgnoreRectangles    - a list of rectangles inside 'theImageRectangle' which Ivy will erase
  663. #                              before creating the 'PICT' resource.
  664. #
  665. #    Outputs:
  666. #        result                - a 32 bit integer representing the checksum value of the image.
  667. #
  668. #    See also:
  669. #        IVError()
  670. #        IVDeleteImageFile()
  671. #
  672. #    Notes:
  673. #        WARNING: This task will delete any existing file named 'theFileName' before creating the
  674. #        new file.
  675. #
  676. #    Example:
  677. #
  678. #        result := IVCreateImageFile( "Pam’s Image File", { 0, 0, 100, 100 } );
  679. #            
  680. #        errorList := IVError();
  681. #        if ( errorList[1] <> 0 )
  682. #        begin
  683. #            println "Could not create the image file - ", errorList;
  684. #        end;
  685. #
  686. Task IVCreateImageFile( theFileName, theImageRectangle, theIgnoreRectangles := { } ) # return boolean
  687. begin
  688.  
  689. #        if ( IVRectangleDefined( theImageRectangle ) = false )
  690. #        begin
  691. #            resultList := { 0, 0, "The rectangle passed to IVCreateImageFile was either undefined or contained an undefined element." };
  692. #            return Call( IVGetExceptionHandler(), resultList );
  693. #        end;
  694.     
  695.     kDupFNErr := -48;
  696.     resultList := { kDupFNErr };
  697.     
  698.     while ( resultList[1] = kDupFNErr )
  699.     begin
  700.         Ivy( "IVDELETEIMAGE", theFileName );
  701.         resultList := Ivy( "IVCREATEIMAGE", theFileName, theImageRectangle, theIgnoreRectangles );
  702.     end;
  703.     
  704.     resultList := HandleResultList( resultList, "IVCreateImageFile" );
  705.     global gIVError := resultList;    
  706.         
  707.     if ( resultList[1] <> 0 )
  708.     begin
  709.         return Call( IVGetExceptionHandler(), resultList );
  710.     end;
  711.         
  712.     if ( global gIVResultList )
  713.         return resultList;
  714.     else
  715.         return resultList[2];
  716.  end;
  717.  
  718.  
  719. #    IVCompareImageFiles( theFirstFileName, theSecondFileName, theResultFileName, theIgnoreRectangles := { } )
  720. #
  721. #    Purpose:
  722. #        To compare two image files.  If the two images differ, the task will create a new image
  723. #        containing the differences.
  724. #
  725. #    Inputs:
  726. #        theFirstFileName    - a string containing the first image’s file name.
  727. #
  728. #        theSecondFileName    - a string containing the second image’s file name.
  729. #
  730. #        theResultFileName    - if the two images do not match, this file name will be used to
  731. #                              create a new image file showing where the first two images differ.
  732. #                              If your script passes an empty string ("" or ''), Ivy will not
  733. #                              create a difference image.
  734. #
  735. #        theIgnoreRectangles    - a list of rectangular areas to ignore when performing the compar-
  736. #                              ison.  Each rectangle (which are lists themselves, of the form
  737. #                              { left, top, right, bottom }) should be expressed in local co-
  738. #                              ordinates relative to the first image; that is, assume the top-left
  739. #                              corner of the first image is (0, 0).
  740. #
  741. #    Outputs:
  742. #        result                 - a Boolean value: '1' means the images matched, '0' means the images
  743. #                              did not match.
  744. #
  745. #    See also:
  746. #        IVCreateImageFile()
  747. #
  748. #    Example:
  749. #
  750. #        result := IVCompareImageFiles( "Yin", "Yang", "Yin&Yang", { { 0, 0, 5, 5 }, { 5, 0, 10, 5 } } );
  751. #            
  752. #        errorList := IVError();
  753. #        if ( errorList[1] <> 0 )
  754. #        begin
  755. #            println "Could not compare the image files - ", errorList;
  756. #        end;
  757. #
  758. Task IVCompareImageFiles( theFirstFileName, theSecondFileName, theResultFileName, theIgnoreRectangles := { } ) # return boolean
  759. begin
  760.     Ivy( "IVDELETEIMAGE", theResultFileName );
  761.     
  762.     resultList := Ivy( "IVCOMPAREIMAGES",    theFirstFileName, 
  763.                                             theSecondFileName, 
  764.                                             theResultFileName,
  765.                                             theIgnoreRectangles );
  766.                                             
  767.     resultList := HandleResultList( resultList, "IVCompareImageFiles" );
  768.     global gIVError := resultList;
  769.     
  770.     if ( resultList[1] <> 0 )
  771.     begin
  772.         return Call( IVGetExceptionHandler(), resultList );
  773.     end;
  774.         
  775.     if ( global gIVResultList )
  776.         return resultList;
  777.     else
  778.         return resultList[2];
  779.  end;
  780.  
  781.  
  782. #    IVGetImageFileInfo( theFileName )
  783. #
  784. #    Purpose:
  785. #        To obtain information about an image that Ivy created.
  786. #
  787. #    Inputs:
  788. #        theFileName    - a string containing the file name of an image.
  789. #
  790. #    Outputs:
  791. #        result        - a list of the following values:  an enclosing rectangle, the bit depth of the
  792. #                      image, the size of the image in bytes, the unsigned 32 bit checksum of the
  793. #                      image, and the time and date the image was created. See the notes below.
  794. #
  795. #    Notes:
  796. #        To ensure future compatibility with Ivy, use the following globals when accessing elements of the list
  797. #        returned by IVGetImageFileInfo.
  798. #
  799. #        global kImageFrame;
  800. #        global kIvyVersion;
  801. #        global kImageSize;
  802. #        global kImageBitMapChecksum;
  803. #        global kImagePixelCount;
  804. #        global kImageBitDepth;
  805. #        global kImageTimeStamp;
  806. #        global kImageDateStamp;
  807. #
  808. #    See also:
  809. #        IVCreateImageFile()
  810. #
  811. #    Example:
  812. #
  813. #        infoList := IVGetImageInfo( "Dialog Image" );
  814. #            
  815. #        errorList := IVError();
  816. #        if ( errorList[1] <> 0 )
  817. #        begin
  818. #            println "Could not set the directory - ", errorList;
  819. #        end
  820. #        else
  821. #            println "The image was created on ", infoList[ global kImageDateStamp ];
  822. #
  823. Task IVGetImageFileInfo( theFileName, theImageName := "" )
  824. begin
  825.     resultList := Ivy( "IVGETIMAGEINFO", theFileName );
  826.     
  827.     resultList := HandleResultList( resultList, "IVGetImageFileInfo" );
  828.     global gIVError := resultList;
  829.     
  830.     if ( resultList[1] <> 0 )
  831.     begin
  832.         return Call( IVGetExceptionHandler(), resultList );
  833.     end;
  834.         
  835.     if ( global gIVResultList )
  836.         return resultList;
  837.     else
  838.         return resultList[2];
  839.  end;
  840.  
  841.  
  842. #--------------------------------------------------------------------------------------------------
  843.  
  844.  
  845. # TASKS TO CALCULATE SCREEN IMAGE CHECKSUMS
  846.  
  847.  
  848. #    IVChecksumRectangle( theScreenRectangle )
  849. #
  850. #    Purpose:
  851. #        To calculate a simple check sum of the screen image enclosed in the 'theScreenRectangle.'
  852. #
  853. #    Inputs:
  854. #        theScreenRectangle    - a list of four values describing a rectangle; e.g. { left, top,
  855. #                              right, bottom }.
  856. #
  857. #    Outputs:
  858. #        result                - an unsigned 32 bit checksum.
  859. #
  860. #    Notes:
  861. #         This task creates a check sum of screen memory.  If screen is running in 2, 4, or 8 bit color mode, the check
  862. #        sum value will be dependent upon the screen’s current color lookup table.
  863. #
  864. #    See also:
  865. #        IVCreateChecksumFile()
  866. #
  867. #    Example:
  868. #
  869. #        result := IVChecksumRectangle( { 0, 0, 20, 30 } );
  870. #            
  871. #        errorList := IVError();
  872. #        if ( errorList[1] <> 0 )
  873. #        begin
  874. #            println "Could not checksum the rectangle - ", errorList;
  875. #        end;
  876. #
  877. Task IVChecksumRectangle( theScreenRectangle ) # return a string representing a 32 bit unsigned integer
  878. begin
  879.     resultList := Ivy( "IVCHECKSUMIMAGE", "", theScreenRectangle, false );
  880.     
  881.     resultList := HandleResultList( resultList, "IVChecksumRectangle" );
  882.     global gIVError := resultList;
  883.     
  884.     if ( resultList[1] <> 0 )
  885.     begin
  886.         return Call( IVGetExceptionHandler(), resultList );
  887.     end;
  888.         
  889.     if ( global gIVResultList )
  890.         return resultList;
  891.     else
  892.         return resultList[2];
  893.  end;
  894.  
  895.  
  896. #    IVCreateChecksumFile( theFileName, theScreenRectangle )
  897. #
  898. #    Purpose:
  899. #        To create a file which contains the check sum of a screen image.
  900. #
  901. #    Inputs:
  902. #        theFileName            - a string containing the name of the new file.
  903. #
  904. #        theScreenRectangle    - a list of four values describing a rectangle; e.g. { left, top,
  905. #                              right, bottom }.
  906. #
  907. #    Outputs:
  908. #        result                - a Boolean value indicating success or failure; 1 is success and
  909. #                              0 is failure.
  910. #
  911. #    Notes:
  912. #
  913. #    This task creates a new file named imageName and stores the 32 bit checksum value in the
  914. #    resource fork of the file; in a type 'IVYC' resource.
  915. #
  916. #    See also:
  917. #            IVChecksumRectangle()
  918. #            IVGetImageFileInfo()
  919. #
  920. #    Example:
  921. #
  922. #            result := IVCreateChecksumFile( "Alice’s Checksum", { 15, 20, 45, 30 } );
  923. #            
  924. #            errorList := IVError();
  925. #            if ( errorList[1] <> 0 )
  926. #            begin
  927. #                println "Could not create the checksum file - ", errorList;
  928. #            end;
  929. #
  930. Task IVCreateChecksumFile( theFileName, theImageRectangle )
  931. begin
  932.     if ( IVRectangleDefined( theImageRectangle ) = false )
  933.     begin
  934.         resultList := { 0, 0, "The rectangle passed to IVCreateChecksumFile was either undefined or contained an undefined element." };
  935.         return Call( IVGetExceptionHandler(), resultList );
  936.     end;
  937.  
  938.     kDupFNErr := -48;
  939.     resultList := { kDupFNErr };
  940.     
  941.     while ( resultList[1] = kDupFNErr )
  942.     begin
  943.         Ivy( "IVDELETEIMAGE", theFileName );
  944.         resultList := Ivy( "IVCHECKSUMIMAGE", theFileName, theImageRectangle, true );
  945.     end;
  946.  
  947.     resultList := HandleResultList( resultList, "IVCreateChecksumFile" );
  948.     global gIVError := resultList;
  949.     
  950.     if ( resultList[1] <> 0 )
  951.     begin
  952.         return Call( IVGetExceptionHandler(), resultList );
  953.     end;
  954.         
  955.     if ( global gIVResultList )
  956.         return resultList;
  957.     else
  958.         return resultList[2];
  959. end;
  960.  
  961.  
  962. #--------------------------------------------------------------------------------------------------
  963.  
  964.  
  965. #    PERFORMANCE TASKS
  966.  
  967. #    IVCallOverhead()
  968. #
  969. #    Purpose:
  970. #        To calculate the round trip overhead time involved in making a call to Ivy.  When using
  971. #        Ivy to time an operation, subtract the result of this call from the difference of your
  972. #        start and stop times; for example:
  973. #
  974. #                        finalTime := stopTime - startTime - IVCallOverhead();
  975. #
  976. #    Inputs:
  977. #        None.
  978. #
  979. #    Outputs:
  980. #        taskValue -    a string representing a 32 bit unsigned integer.  The number represents the
  981. #                    time (in milliseconds) it took to make a call to, and return from, Ivy.
  982. #
  983. #    Notes:
  984. #         Applicable notes.
  985. #
  986. #    See also:
  987. #        Task()
  988. #
  989. #    Example:
  990. #
  991. #        overheadTime := IVCallOverhead();
  992. #            
  993. #        errorList := IVError();
  994. #        if ( errorList[1] <> 0 )
  995. #        begin
  996. #            println "Could not get the overhead time - ", errorList;
  997. #        end;
  998. #
  999. task IVCallOverhead()
  1000. begin
  1001.     kTrips := 3;
  1002.             
  1003.     total := 0;
  1004.     for i := 1 to kTrips
  1005.     begin
  1006.         startTime := IVGetCurrentTime();
  1007.         stopTime  := IVGetCurrentTime();
  1008.                                 
  1009.         delta := IVSubtractTimes( stopTime, startTime );
  1010.         
  1011.         if ( typeOf( delta ) = 'String' )
  1012.             delta := StrToNum( delta );
  1013.                 
  1014.         total := total + delta;
  1015.     end;
  1016.         
  1017.     return NumToStr( total / kTrips );
  1018. end;
  1019.  
  1020.  
  1021. #    IVPoll( theJobID )
  1022. #
  1023. #    Purpose:
  1024. #        To poll for the results of an asynchronous task call; in this version of Ivy, you can call
  1025. #        only IVWaitForImage asynchronously.
  1026. #
  1027. #    Inputs:
  1028. #        theJobID    - the asynchronous job ID.
  1029. #
  1030. #    Outputs:
  1031. #        result        - until the asynchronous task completes, ‘result’ will contain a list of
  1032. #                      two values: { 1, theJobID }.  Once the asynchronous task completes, ‘result’
  1033. #                      will contain the result corresponding the asynchronous task.
  1034. #
  1035. #    Notes:
  1036. #        See the section titled “Calling External Tools Asynchronously” in the “Using External Tools” chapter of the
  1037. #        “Virtual User Language Reference.”
  1038. #
  1039. #    See also:
  1040. #        IVWaitForImage()
  1041. #
  1042. #    Example:
  1043. #                    
  1044. #        resultList := IVWaitForImage( "Cindy’s slipper", { 0, 0, 100, 100 }, 5 );    # Make an asynchronous task call
  1045. #        jobID = resultList[2];
  1046. #                                                                                                                                                                # Now poll until the asynchronous task call finishes.
  1047. #        while ( resultList[1] = 1 and resultList[2] = jobID ) do                    # Make sure you check for the job ID.
  1048. #        if ( resultList[1] <> 0 )
  1049. #        begin
  1050. #            resultList := IVPoll( jobID );
  1051. #        end;
  1052. #
  1053. Task IVPoll( theJobID )
  1054. begin
  1055.     resultList := Ivy( "POLL", theJobID );
  1056.     global gIVError := resultList;
  1057.     
  1058.     if ( resultList[1] = 1 and resultList[2] = theJobID )
  1059.     begin
  1060.         return resultList;
  1061.     end;
  1062.     else
  1063.     begin
  1064.         if ( resultList[1] <> 0 )
  1065.         begin
  1066.             resultList := HandleResultList( resultList, "IVPoll asynchronous job " + theJobID );
  1067.             return Call( IVGetExceptionHandler(), resultList );
  1068.         end;
  1069.         else
  1070.         begin
  1071.             if ( global gIVResultList )
  1072.                 return resultList;
  1073.             else
  1074.                 return resultList[2];
  1075.         end; 
  1076.     end;
  1077. end;
  1078.  
  1079.  
  1080. #    IVCancel( theJobID )
  1081. #
  1082. #    Purpose:
  1083. #        To cancel a call to an asynchronous task call; in this version of Ivy, you can call
  1084. #        only IVWaitForImage asynchronously.
  1085. #
  1086. #    Inputs:
  1087. #        theJobID    - the asynchronous job ID.
  1088. #
  1089. #    Outputs:
  1090. #        result        - an error code.
  1091. #
  1092. #    Notes:
  1093. #        See the section titled “Calling External Tools Asynchronously” in the “Using External Tools”
  1094. #        chapter of the “Virtual User Language Reference.”
  1095. #
  1096. #    See also:
  1097. #        IVPoll()
  1098. #
  1099. #    Example:
  1100. #
  1101. #        resultList := IVWaitForImage( "Cindy’s slipper", { 0, 0, 100, 100 }, 5 );    # Make an asynchronous task call
  1102. #        jobID = resultList[2];
  1103. #
  1104. #        result := IVCancel( jobID );                                                                                    # Now cancel the asynchronous task call.
  1105. #
  1106. Task IVCancel( theJobID )
  1107. begin
  1108.     resultList := Ivy( "CANCEL", theJobID );
  1109.     
  1110.     resultList := HandleResultList( resultList, "IVCancel" );
  1111.     global gIVError := resultList;
  1112.  
  1113.     if ( resultList[1] <> 0 )
  1114.     begin
  1115.         return Call( IVGetExceptionHandler(), resultList );
  1116.     end;
  1117.  
  1118.     return resultList[1];
  1119. end;
  1120.  
  1121.  
  1122. #    IVWaitForImage( theFileName, theWaitingRectangle, theCPUPercentage := 5 )
  1123. #
  1124. #    Purpose:
  1125. #        This is an asynchronous task.  Before using this task, read and understand the section titled “Calling External
  1126. #        Tools Asynchronously” in the “Using External Tools” chapter of the “Virtual User Language Reference.”
  1127. #            
  1128. #        This task installs an Ivy interrupt routine on the target. The interrupt routine will watch for an image and
  1129. #        detect when the image first appears.
  1130. #
  1131. #    Inputs:
  1132. #        theFileName    - a string containing the file name of the image.
  1133. #
  1134. #        theWaitRectangle    - the EXACT screen location where the image will appear; { left, top,
  1135. #                              right, bottom }.
  1136. #
  1137. #        theCPUPercentage    - the percent of CPU time the task should use while looking for an image.
  1138. #
  1139. #    Outputs:
  1140. #        result                - a list of four values: { startTime, timeFound, ivyUsed, frequency }
  1141. #
  1142. #        startTime            - an 32 bit integer indicating the time (in milliseconds) when Ivy
  1143. #                              started looking for the image.
  1144. #
  1145. #        timeFound            - an 32 bit integer indicating the time (in milliseconds) when Ivy
  1146. #                              first "saw" the image appear on the screen.
  1147. #
  1148. #        ivyUsed                - an 32 bit integer indicating the time (in milliseconds) used by Ivy
  1149. #                              while waiting for the image to appear.
  1150. #
  1151. #        frequency            - an 32 bit integer indicating the time interval (in milliseconds) at
  1152. #                              which Ivy checked the screen to see if the image appeared.
  1153. #
  1154. #    Notes:
  1155. #        See the section titled “Calling External Tools Asynchronously” in the “Using External Tools” chapter of the
  1156. #        “Virtual User Language Reference.”
  1157. #
  1158. #    See also:
  1159. #        IVPoll()
  1160. #        IVCancel()
  1161. #
  1162. #    Example:
  1163. #
  1164. #        resultList := IVWaitForImage( "Achille’s Thumb", { 20, 100, 25, 100 }, 5 );
  1165. #        jobID := resultList[2];
  1166. #
  1167. #        pressMouse;                                                                                                                                    # Start the operation you're timing
  1168. #            
  1169. #        while ( resultList[1] = 1 and resultList[2] = jobID )                                                # Poll until Ivy finds the image
  1170. #        begin
  1171. #            resultList := IVPoll( jobID );
  1172. #        end;
  1173. #
  1174. #        releaseMouse;                                                                                                                                # Stop the operation, if necessary
  1175. #
  1176. #        waitResultList := resultList;                                                                                                # Get the results of the task call
  1177. #
  1178. #        totalTime := IVSubtractTimes( waitResultList[2], waitResultList[1] );    # Subtract the startTime from the timeFound
  1179. #
  1180. #        operationTime := IVSubtractTimes( totalTime, waitResultList[3] );        # Subtract off the time Ivy used wait for the image
  1181. #
  1182. Task IVWaitForImage( theFileName, theWaitingRectangle, theCPUPercentage := 5 )
  1183. begin
  1184.  
  1185.     if ( IVRectangleDefined( theWaitingRectangle ) = false )
  1186.     begin
  1187.         resultList := { 0, 0, "The rectangle passed to IVWaitForImage was either undefined or contained an undefined element." };
  1188.         return Call( IVGetExceptionHandler(), resultList );
  1189.     end;
  1190.     
  1191.     resultList := Ivy( "IVWAITFORIMAGE", theFileName, theWaitingRectangle, theCPUPercentage ) async: TRUE;
  1192.     global gIVError := resultList;
  1193.     
  1194.     if ( resultList[1] <> 1 or isUndefined( resultList[2] ) )
  1195.     begin
  1196.         resultList := HandleResultList( resultList, "IVWaitForImage" );
  1197.         
  1198.         return Call( IVGetExceptionHandler(), resultList );
  1199.     end;
  1200.  
  1201.     return resultList;
  1202. end;
  1203.  
  1204.  
  1205. #    IVStartWaitForImage( theFileName, theWaitingRectangle, theCPUPercentage )
  1206. #
  1207. #    Purpose:
  1208. #        To install the Ivy interrupt routine on the target that will watch for an image and time
  1209. #        when the image appears.
  1210. #
  1211. #    Inputs:
  1212. #        theFileName            - a string containing the file name of the image.
  1213. #
  1214. #        theWaitRectangle    - the exact screen location where the image will appear; { left, top,
  1215. #                              right, bottom }.
  1216. #
  1217. #        theCPUPercentage    - the percent of CPU time the task should use while looking for an image.
  1218. #
  1219. #    Outputs:
  1220. #        result                - a list of two values: { startTime, frequency }
  1221. #
  1222. #        startTime            - an unsigned 32 bit integer indicating the time (in milliseconds) 
  1223. #                              of the target machine when the task was installed.
  1224. #
  1225. #        frequency            - an unsigned 32 bit integer indicating the time interval (in mill-
  1226. #                              iseconds) at which Ivy checked the screen to see if the image appeared.
  1227. #
  1228. #    Notes:
  1229. #         A millisecond equals 1/1000th of a second.
  1230. #
  1231. #    See also:
  1232. #            IVGetTimeFound()
  1233. #            IVRemoveWaitForImageFile()
  1234. #            IVGetCurrentTime()
  1235. #            IVSubtractTimes()
  1236. #
  1237. #    Example:
  1238. #
  1239. #            result := IVStartWaitForImage( "Achille’s Thumb", { 20, 100, 25, 100 }, 5 );
  1240. #
  1241. Task IVStartWaitForImage( theFileName, theWaitingRectangle, theCPUPercentage )
  1242. begin
  1243.  
  1244.     if ( IVRectangleDefined( theWaitingRectangle ) = false )
  1245.     begin
  1246.         resultList := { 0, 0, "The rectangle passed to IVStartWaitForImage was either undefined or contained an undefined element." };
  1247.         return Call( IVGetExceptionHandler(), resultList );
  1248.     end;
  1249.     
  1250.     resultList := Ivy( "IVSTARTWAITFORIMAGE", theFileName, theWaitingRectangle, theCPUPercentage );
  1251.     
  1252.     resultList := HandleResultList( resultList, "IVStartWaitForImage" );
  1253.     global gIVError := resultList;
  1254.     
  1255.     if ( resultList[1] <> 0 )
  1256.     begin
  1257.         return Call( IVGetExceptionHandler(), resultList );
  1258.     end;
  1259.         
  1260.     if ( global gIVResultList )
  1261.         return resultList;
  1262.     else
  1263.         return resultList[2];
  1264.  end;
  1265.  
  1266.  
  1267. #    IVGetTimeFound()
  1268. #
  1269. #    Purpose:
  1270. #        To determine when the Ivy interrupt routine first found the image for which it was asked to wait.
  1271. #
  1272. #    Inputs:
  1273. #        None.
  1274. #
  1275. #    Outputs:
  1276. #        result - a string containing an unsigned 32 bit integer.  The integer is the time (in milli-
  1277. #                 seconds) of the target machine when Ivy first spotted the image.  If the image has
  1278. #                 not yet appeared, IVGetTimeFound() will return 0.
  1279. #
  1280. #    Notes:
  1281. #         A millisecond equals 1/1000th of a second.
  1282. #
  1283. #    See also:
  1284. #        IVStartWaitForImage()
  1285. #        IVStopWaitForImage()
  1286. #        IVWaitForImage()
  1287. #
  1288. #    Example:
  1289. #
  1290. #        resultList := IVGetTimeFound();
  1291. #
  1292. Task IVGetTimeFound()
  1293. begin
  1294.     resultList := Ivy( "IVGETTIMEFOUND", 0 );
  1295.  
  1296.     resultList := HandleResultList( resultList, "IVGetTimeFound" );
  1297.     global gIVError := resultList;
  1298.     
  1299.     if ( resultList[1] <> 0 )
  1300.     begin
  1301.         return Call( IVGetExceptionHandler(), resultList );
  1302.     end;
  1303.     
  1304.     if ( global gIVResultList )
  1305.         return resultList;
  1306.     else
  1307.         return resultList[2];
  1308.  end;
  1309.  
  1310.  
  1311. #    IVStopWaitForImage()
  1312. #
  1313. #    Purpose:
  1314. #        To remove the Ivy “wait for image” interrupt routine and to find out how much time (in milliseconds)
  1315. #        the interrupt routine used while waiting for the image to appear.
  1316. #
  1317. #    Inputs:
  1318. #        None.
  1319. #
  1320. #    Outputs:
  1321. #        result - a string representing an unsigend 32 bit integer.  The integer represents the
  1322. #                 time (in milliseconds) used by Ivy while waiting for the image to appear.
  1323. #
  1324. #    Notes:
  1325. #         A millisecond equals 1/1000th of a second.
  1326. #
  1327. #    See also:
  1328. #        IVStartWaitForImage()
  1329. #        IVGetTimeFound()
  1330. #
  1331. #    Example:
  1332. #
  1333. #        resultList := IVStopWaitForImage();
  1334. #
  1335. Task IVStopWaitForImage()
  1336. begin
  1337.     resultList := Ivy( "IVSTOPWAITFORIMAGE", 0 );
  1338.     
  1339.     resultList := HandleResultList( resultList, "IVStopWaitForImage" );
  1340.     global gIVError := resultList;
  1341.     
  1342.     if ( resultList[1] <> 0 )
  1343.     begin
  1344.         return Call( IVGetExceptionHandler(), resultList );
  1345.     end;
  1346.     
  1347.     if ( global gIVResultList )
  1348.         return resultList;
  1349.     else
  1350.         return resultList[2];
  1351.  end;
  1352.  
  1353.  
  1354. #    IVGetCurrentTime()
  1355. #
  1356. #    Purpose:
  1357. #        To get the current time (in milliseconds) of the target machine.
  1358. #
  1359. #    Inputs:
  1360. #        None.
  1361. #
  1362. #    Outputs:
  1363. #        result - a string represent a 32 bit unsigned integer.  The integer represents the time (in milliseconds)
  1364. #                 of the target machine; the machine upon which Ivy is running.
  1365. #
  1366. #    Notes:
  1367. #         A millisecond equals 1/1000th of a second.
  1368. #
  1369. #    See also:
  1370. #        IVSubtractTimes()
  1371. #
  1372. #    Example:
  1373. #
  1374. #        resultList := IVGetCurrentTime();
  1375. #
  1376. Task IVGetCurrentTime()
  1377. begin
  1378.     resultList := Ivy( "IVGETCURRENTTIME" );
  1379.     
  1380.     resultList := HandleResultList( resultList, "IVGetCurrentTime" );
  1381.     global gIVError := resultList;
  1382.     
  1383.     if ( resultList[1] <> 0 )
  1384.     begin
  1385.         return Call( IVGetExceptionHandler(), resultList );
  1386.     end;
  1387.     
  1388.     if ( global gIVResultList )
  1389.         return resultList;
  1390.     else
  1391.         return resultList[2];
  1392.  end;
  1393.  
  1394.  
  1395. #    IVSubtractTimes( theMinuend, theSubtrahend ))
  1396. #
  1397. #    Purpose:
  1398. #        To subtract two strings representing unsigned 32 bit integers.
  1399. #
  1400. #    Inputs:
  1401. #        theMinuend        - the number from which the theSubtrahend is subtracted.
  1402. #        theSubtrahend    - the number subtracted from the minuend; e.g., theMinuend - theSubtrahend = theDifference.
  1403. #
  1404. #    Outputs:
  1405. #        result            - a string representing a 32 bit unsigned integer.
  1406. #
  1407. #    Notes:
  1408. #         Use the Virtual User’s built-in task StrToNum() to convert the result of IVSubtractTimes() into a
  1409. #        V.U. integer.  If the string represents a number greater than 32767, StrToNum() will return 'undefined'.
  1410. #
  1411. #    See also:
  1412. #        IVGetCurrentTime()
  1413. #        IVGetTimeFound()
  1414. #
  1415. #    Example:
  1416. #
  1417. #        result := IVSubtractTimes( "45900", "45800" );
  1418. #
  1419. #        theDifference := StrToNum( resultList[2] );
  1420. #
  1421. Task IVSubtractTimes( theMinuend, theSubtrahend )
  1422. begin
  1423.     resultList := Ivy( "IVSUBTRACTTIMES", theMinuend, theSubtrahend );
  1424.     
  1425.     resultList := HandleResultList( resultList, "IVSubtractTimes" );
  1426.     global gIVError := resultList;
  1427.     
  1428.     if ( resultList[1] <> 0 )
  1429.     begin
  1430.         return Call( IVGetExceptionHandler(), resultList );
  1431.     end;
  1432.     
  1433.     if ( global gIVResultList )
  1434.         return resultList;
  1435.     else
  1436.         return resultList[2];
  1437.  end;
  1438.  
  1439.  
  1440. #--------------------------------------------------------------------------------------------------
  1441.  
  1442.  
  1443. #    ÏÏÏ        SEARCH TASKS
  1444.  
  1445.  
  1446. #    IVLocateImageFile( theFileName, theSearchRectangle, theLastLocation := { -32767, -32767 } )
  1447. #
  1448. #    Purpose:
  1449. #        To find the location of a screen image.
  1450. #
  1451. #    Inputs:
  1452. #        theFileName    - a string containing the file name of the image.
  1453. #
  1454. #        theLocation    - the screen rectangle in which to search; { left, top, right, bottom }.
  1455. #
  1456. #        theLastLocation - the rectangle (or just its left and top points) where Ivy last found the image.  Use
  1457. #                          this parameter to find the next occurance of an image inside a given search rectangle.
  1458. #
  1459. #    Outputs:
  1460. #        result        - a rectangle describing the location of the image; { left, top, right, bottom }.
  1461. #
  1462. #    Notes:
  1463. #         If the task does not find the image, it returns the following rectangle { 0, 0, 0, 0 }.
  1464. #
  1465. #    See also:
  1466. #        IVLocateString()
  1467. #
  1468. #    Example:
  1469. #
  1470. #        resultList := IVLocateImageFile( "The lost image", { 0, 0, 640, 480 } );
  1471. #
  1472. Task IVLocateImageFile( theFileName, theSearchRectangle, theLastLocation := { -32767, -32767 } )
  1473. begin
  1474.  
  1475.     if ( IVRectangleDefined( theSearchRectangle ) = false )
  1476.     begin
  1477.         resultList := { 0, 0, "The rectangle passed to IVLocateImageFile was either undefined or contained an undefined element." };
  1478.         return Call( IVGetExceptionHandler(), resultList );
  1479.     end;
  1480.     
  1481.     resultList := Ivy( "IVLOCATEIMAGE", theFileName, theSearchRectangle, theLastLocation );
  1482.     
  1483.     resultList := HandleResultList( resultList, "IVLocateImageFile" );
  1484.     global gIVError := resultList;
  1485.     
  1486.     if ( resultList[1] <> 0 )
  1487.     begin
  1488.         return Call( IVGetExceptionHandler(), resultList );
  1489.     end;
  1490.         
  1491.     if ( global gIVResultList )
  1492.         return resultList;
  1493.     else
  1494.         return resultList[2];
  1495.  end;
  1496.  
  1497.  
  1498. #    IVLocateString( theSearchString, theSearchRect, theFontName, theFontSize, theFontStyle := 0, theLastLocation := { -32767, -32767 } )
  1499. #
  1500. #    Purpose:
  1501. #        To locate a string of characters on the screen.
  1502. #
  1503. #    Inputs:
  1504. #        theSearchString    - a string containing the characters for which to look.
  1505. #
  1506. #        theSearchRect    - the screen rectangle in which to look.
  1507. #
  1508. #        theFontName        - the font name in which the string will appear.
  1509. #
  1510. #        theFontSize        - the size of the font.
  1511. #
  1512. #        theFontStyle    - the font style; that is, normal, bold, underline, italic, shadow,
  1513. #                          outline, extend, condense.
  1514. #
  1515. #        theLastLocation - the rectangle (or just its left and top points) where Ivy last found the string.  Use
  1516. #                          this parameter to find the next occurance of a string inside a given search rectangle.
  1517. #
  1518. #    Outputs:
  1519. #            result        - a rectangle describing the location of the image; { left, top,
  1520. #                          right, bottom }.
  1521. #
  1522. #    Notes:
  1523. #         If the task does not find the image, it returns the following rectangle { 0, 0, 0, 0 }.
  1524. #        To create a font style add the following global constants together in any combination.
  1525. #
  1526. #            global kNormal;
  1527. #            global kBold;
  1528. #            global kItalic;
  1529. #            global kUnderline;
  1530. #            global kOutline;
  1531. #            global kShadow;
  1532. #            global kCondense;
  1533. #            global kExtend;
  1534. #
  1535. #    See also:
  1536. #        IVLocateString()
  1537. #
  1538. #    Example:
  1539. #
  1540. #        global kBold;
  1541. #        global kItalic;
  1542. #
  1543. #        resultList := IVLocateString( "Hide me", { 0, 0, 640, 480 }, "Chicago", 12, kBold + kItalic );
  1544. #
  1545. Task IVLocateString( theSearchString, theSearchRect, theFontName, theFontSize, theFontStyle := 0, theLastLocation := { -32767, -32767 } )
  1546. begin
  1547.  
  1548.     if ( IVRectangleDefined( theSearchRect ) = false )
  1549.     begin
  1550.         resultList := { 0, 0, "The rectangle passed to IVLocateString was either undefined or contained an undefined element." };
  1551.         return Call( IVGetExceptionHandler(), resultList );
  1552.     end;
  1553.     
  1554.     resultList := Ivy( "IVLOCATESTRING", theSearchString, theSearchRect, theFontName, theFontSize, theFontStyle, theLastLocation );
  1555.     
  1556.     resultList := HandleResultList( resultList, "IVLocateString" );
  1557.     global gIVError := resultList;
  1558.     
  1559.     if ( resultList[1] <> 0 )
  1560.     begin
  1561.         return Call( IVGetExceptionHandler(), resultList );
  1562.     end;
  1563.         
  1564.     if ( global gIVResultList )
  1565.         return resultList;
  1566.     else
  1567.         return resultList[2];
  1568.  end;
  1569.